gh-146636: PEP 803: Reference documentation by encukou · Pull Request #148013 · python/cpython

encukou · 2026-04-02T14:17:02Z

Issue: Implement PEP 803 -- abi3t #146636

📚 Documentation preview 📚: https://cpython-previews--148013.org.readthedocs.build/

Doc/whatsnew/3.15.rst

ZeroIntensity

Congrats on the PEP acceptance :)

Mostly editorial comments from me. The content generally looks good.

Doc/c-api/module.rst

Doc/c-api/stable.rst

ZeroIntensity · 2026-04-02T14:45:47Z

Doc/c-api/stable.rst

+Note that compiling for Stable ABI is *not* a complete guarantee that code will
+be compatible with the expected Python versions.
+Stable ABI prevents *ABI* issues, like linker errors due to missing


I think we need to precede "Stable ABI" with "the"?

Suggested change

Note that compiling for Stable ABI is *not* a complete guarantee that code will

be compatible with the expected Python versions.

Stable ABI prevents *ABI* issues, like linker errors due to missing

Note that compiling for the Stable ABI is *not* a complete guarantee that code will

be compatible with the expected Python versions.

The Stable ABI prevents *ABI* issues, like linker errors due to missing

Even if there's two of them?

Yeah, not too sure about the rules here. What about "the Stable ABIs"?

The way I wrote it still sounds best to me...

ZeroIntensity · 2026-04-02T14:51:25Z

Doc/c-api/stable.rst

+symbols or data corruption due to changes in structure layouts or function
+signatures.
+However, other changes in Python can change the *behavior* of extensions.
+See Python's Backwards Compatibility Policy (:pep:`387`) for details.


This sentence confused me a little when I first read it. I had read it as "We might change the behavior of extensions -- go read our backward compatibility policy if you want to know what", but then we provide an example right after the reader was diverted. Could we move this sentence to after the following paragraph, or put it in a seealso note?

Doc/whatsnew/3.15.rst

ZeroIntensity · 2026-04-02T14:57:07Z

Doc/whatsnew/3.15.rst

+  part of the instance struct; and
+- Switching from a ``PyInit_`` function to a new export hook,
+  :c:func:`PyModExport_* <PyModExport_modulename>`, introduced for this
+  purpose in :pep:`903`.


Suggested change

purpose in :pep:`903`.

purpose in :pep:`803`.

Doc/whatsnew/3.15.rst

ZeroIntensity · 2026-04-02T15:00:06Z

Doc/whatsnew/3.15.rst

+be selected in a build tool (such as Setuptools, ``meson-python``, Cython,
+Scikit-build-core, Maturin, and similar).


Is it intentional that meson-python is the only package in a code block here?

Doc/whatsnew/3.15.rst

StanFromIreland · 2026-04-02T15:47:41Z

The new check caught removals: https://github.com/python/cpython/actions/runs/23907059205/job/69719041532?pr=148013 (and on your PR out of everyone's ;-)

Doc/c-api/stable.rst

Doc/whatsnew/3.15.rst

ngoldbaum

Thanks for putting this together! I left a few comments inline, please take them or leave them as you see fit.

ngoldbaum · 2026-04-03T17:22:37Z

Doc/c-api/module.rst

   defined this way.

+   In the :ref:`Stable ABI <stable-abi>` for free-threaded builds (``abi3t``),
+   this struct is opaque, and unusable in practice.


This is all covered above, but for people who land here with a direct link to this section, you could add a cross-reference suggesting the PyModExport API instead?

ngoldbaum · 2026-04-03T17:25:28Z

Doc/c-api/stable.rst

+   When using a build tool (for example, ``setuptools``), the tool is
+   generally responsible for setting macros and synchronizing them with
+   extension filenames and other metadata.
+   Prefer using the tool's options over defining the macros manually.


Maybe setuptools is a poor example to use above then? Because setuptools expects users to set the build flags manually...

You could delete the "(For example, SetupTools)" above, or maybe refer to meson-python or scikit-build-core instead? These days that's what I recommend to people depending on if they already use CMake or not.

AFAIK Setuptools is the most widely known build tool; the example is there to clarify what kind of “build tool” I'm talking about.

Setuptools has a --py_limited_api argument. All tools will ideally need an update for abi3t.

Doc/c-api/stable.rst

ngoldbaum · 2026-04-03T17:30:27Z

Doc/c-api/stable.rst


-The goal for the Limited API is to allow everything that is possible with the
+- define both :c:macro:`!Py_LIMITED_API` and :c:macro:`!Py_TARGET_ABI3T`, or
+- define only :c:macro:`!Py_LIMITED_API` and build for free-threaded Python.


Suggested change

- define only :c:macro:`!Py_LIMITED_API` and build for free-threaded Python.

- Define only :c:macro:`!Py_LIMITED_API` and define :c:macro:`!Py_GIL_DISABLED`.

This happens automatically with a free-threaded interpreter, except on Windows.

I think defining Py_GIL_DISABLED "manually" is still only supported on Windows.

ngoldbaum · 2026-04-03T17:34:45Z

Doc/whatsnew/3.15.rst

+free-threading (``cp315t``) separately.
+
+Stable ABI for Free-Threaded Builds should typically
+be selected in a build tool (such as Setuptools, meson-python, Cython,


Maybe split this between build backends and bindings generators? Both probably need configuration.

It's a little confusing to group Cython in with meson-python.

Guess it's best to drop Cython from the examples.

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

encukou added 3 commits April 2, 2026 15:03

abi3t docs

8e203eb

Manifest, annotations

c1d7fef

Fixup

f83f6b4

encukou requested review from AA-Turner, ZeroIntensity, ericsnowcurrently and hugovk as code owners April 2, 2026 14:17

bedevere-app bot added the awaiting core review label Apr 2, 2026

bedevere-app bot mentioned this pull request Apr 2, 2026

Implement PEP 803 -- abi3t #146636

Open

8 tasks

AIdjis reviewed Apr 2, 2026

View reviewed changes

Doc/whatsnew/3.15.rst Outdated Show resolved Hide resolved

AIdjis reviewed Apr 2, 2026

View reviewed changes

Doc/whatsnew/3.15.rst Outdated Show resolved Hide resolved

I'm not good with numbers

b3e31c6

ZeroIntensity reviewed Apr 2, 2026

View reviewed changes

encukou added 3 commits April 3, 2026 10:53

Merge in the main branch

2372da9

Address review

b3799de

Add a blurb for the PEP

3bc47ee

hugovk reviewed Apr 3, 2026

View reviewed changes

ngoldbaum reviewed Apr 3, 2026

View reviewed changes

encukou and others added 2 commits April 6, 2026 12:06

Apply suggestions from code review

30d97b1

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Respond to reviews

e7e102a

		be selected in a build tool (such as Setuptools, ``meson-python``, Cython,
		Scikit-build-core, Maturin, and similar).

	- define only :c:macro:`!Py_LIMITED_API` and build for free-threaded Python.
	- Define only :c:macro:`!Py_LIMITED_API` and define :c:macro:`!Py_GIL_DISABLED`.
	This happens automatically with a free-threaded interpreter, except on Windows.

Uh oh!

Conversation

encukou commented Apr 2, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

StanFromIreland commented Apr 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ngoldbaum left a comment

Choose a reason for hiding this comment

Uh oh!

ngoldbaum Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

encukou commented Apr 2, 2026 •

edited by github-actions bot

Loading

ngoldbaum Apr 3, 2026 •

edited

Loading